'.\" t
.TH "clstartapp" "1M" "Jun 26, 2006" "1\&.2\&.0"
.SH NAME
clstartapp \- Start application in Linuxha.net Cluster

.SH SYNOPSIS
.TS
l.
clstartapp  \fB-A|--application\fP \fIapp\fP [\fB-V|--verbose\fP] [\fB--checks\fP]
           [\fB-F|--force\fP | \fB--reallyforce\fP] [\fB--maxdelay\fP \fIsecs\fP]
           [\fB--logcmd\fP] [\fB--nolocking\fP] [\fB--nochecksums\fP] [\fB--fsonly\fP]
           [\fB--ignoreapp\fP] [\fB-C|--config\fP \fIfile\fP] [\fB--noremote\fP]
           [\fB-D|--debug\fP] [\fB--file\fP \fIfile\fP]
       Start the cluster locking daemon

clstartapp \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
This is the low-level command that is used to start the specified
application on the local host. Many administrators may choose never
to use this command directly, and instead the \fIclrunapp(1M)\fP command.

However it is useful to understand the use of this command
since in certain recovery conditions it's direct use is recommended. Also
by using this command directly with the \fB--verbose\fP option it provides 
useful feedback to the administrator when either applications take a
long period of time to start, or a particular problem is occurring.

Please note that this command is classed as 'low-level' for the
following reasons:

.TP 4
.B *
It only starts the specified application running on the node that
the command itself is run on.
.TP
.B *
The command allows the application in question to be started, (in
certain circumstances), even if the cluster daemons are not running.
This is a feature not a bug!
.TP
.B *
The command does not take account of any application dependencies or
preferred node settings.
.TP
.B *
The command is unable to reset the preferred nodes for an application.
If this command is used on a node which is not suitable the start-up
of the application will be aborted.

.SH ARGUMENTS
.TP 4
.B -A,--application
This mandatory argument is followed by the name of the application to
start. The application configured must have been validated, even if
the cluster daemons are not running.
.TP
.B -F,--force
Force the start-up of the application. This flag is necessary when
when certain conditions would normally fail resulting in the application
not starting. Such conditions include:

.RS 4
.TP 4
.B *
Only a single node is currently running and so that node is
unable to determine whether it has up to date synchronised data.
.TP
.B *
The cluster daemons are not running - hence the tool is unable to
determine whether the application in question is running on the
other node [though it always attempts a guess by using \fIping(1)\fP
on an IP address associated with the application].
.RE
.TP 4
.B --reallyforce
Attempts to overcome almost all sanity checks and get the application 
up and running. When this flag is used (recommend using carefully) - it
will overcome the following problems.

.RS 4
.TP 4
.B *
Attempts to start the application even if not registered with the cluster.
.TP
.B *
Attempts to start the application even if communication with a cluster 
daemon locally is not possible.
.TP
.B *
Forces the local data copy to be 'primary'.  If the underlying replication 
device thinks that the local copy is not suitable for writing since it 
is not the 'current' copy then by default the start-up of the 
application will fail. When \fB--reallyforce\fP is used then it will
override this and force the local version current.
.RE

.TP 4
.B -V,--verbose
Verbose mode - produce a significant number of progress messages as the 
specified application is started, rather than just warnings and errors.
.TP 
.B --maxdelay
Allows the maximum time to start the application configured in the applicatino
configuration file to be overridden. If the 'maxstarttime' is not configured
for the application, and use of the \fB--maxdelay\fP does not appear in the
\fIclstartapp(1M)\fP command line, then this defaults to 60 seconds.

.TP
.B --ignoreapp
Usually if the return code from the script specified to the
start the application returns a non-zero return code the start-up of
the application is aborted. 

There are of course occasions when it is useful to continue to make the
cluster application available. When the \fB--ignoreapp\fP flag is 
specified the application return code will be treated as a warning
only and continue to start the application.

Note that the \fBLems\fP daemon for the application will still be started and if
this monitor continues to run, it will detect the application is not currently
running on the current node and may eventually fail over to the other node in
the cluster.

For debugging general problems the \fB--fsonly\fP flag (described next),
is sometimes a little more useful.

.TP
.B --fsonly
When this flag is specified the cluster software does not perform
a full start-up of the application. It performs the work necessary
to make the file systems available and no more. 

In this case changes to the file systems contents whilst the
application remains 'off-line' can take place. Since the application
is not truly running the following command will be necessary
to unmount the file systems once use of the file systems is complete:

.TS
l.
clhaltapp --application X --force
.TE

.TP
.B --checks
When this option is selected the utility will attempt to perform even more
validation than normal, including:

.RS 4
.TP 4
.B *
Validate tha the settings in the global sections are configured.
.TP
.B *
Node configuration checking - ensure that at most two nodes are configured,
and one of the nodes is the local machine.
.TP
.B *
Ensure the name of the application in question in the configuration file
is the same as that specified on the command line.
.TP
.B *
.RE

.TP 4
.B --logcmd
The detailed information on every external command that is run is added
to the log file, along with any standard output and standard error
information as well.
.TP
.B --nolocking
Do not attempt to use locking. If this option is not specified locking will
be used if the Linuxha.net locking daemon [see \fIcllockd(1M)\fP] is running 
and provides a port to attempt locking on.
.TP
.B --nochecksums
Normally if the cluster or application configuration file 
have been modified whilst the cluster is running the
checksums which are used to indicate the last sane and checked configuration 
will not be valid. In such instances many of the Linuxha.net commands, including
this will not will not function. If necessary the \fB--nochecksums\fP can be
used to overcome this until the cluster or application configuration are
next rebuilt.
.TP
.B -D,--debug
Include additional output in the logging to help debug problems. Usually
not required for release software versions.
.TP
.B -C,--config
Specifies the name of an alternative cluster configuration file. This is
typically used by developers and can be ignored in most cases.
.TP
.B --noremote
If the remote node is not available specifying this flag will reduce the
application start-up time by several seconds, since no probing [and waiting
for a time-out] pf the remote node will be performed.

.SH FILES
The following files are referenced by this utility as it runs:

.TP 4
.B /etc/cluster/clconf.xml
This file contains the cluster configuration - including almost all settings apart from the resources available/allocated. 
.TP
.B /etc/cluster/APP/appconf.xml
This file exists for each configured application [where 'APP' is the name
of the application] - and contains the configuration of the current 
application that is being started.

.SH SEE ALSO
.TS
l l.
clform(1M)	- High level cluster formation utility
clstartapp(1M)	- Low level application starting tool
clrunapp(1M)	- High level application starting tool
cldeamon(1M)	- Cluster status Daemon
clstat(1M)	- Show cluster status information (including locks)
clconf.xml(5)	- Overall cluster topology configuration file
.TE

.SH AUTHOR
The \fIclstartapp(1M)\fP utility was written by Simon Edwards, 2003-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

